home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / serien / purity / nr.51 / xpk / docs / xpk.doc < prev    next >
Text File  |  1995-08-27  |  16KB  |  500 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/XpkClose
  4. xpkmaster.library/XpkExamine
  5. xpkmaster.library/XpkExamineTags
  6. xpkmaster.library/XpkOpen
  7. xpkmaster.library/XpkOpenTags
  8. xpkmaster.library/XpkPack
  9. xpkmaster.library/XpkPackTags
  10. xpkmaster.library/XpkQuery
  11. xpkmaster.library/XpkQueryTags
  12. xpkmaster.library/XpkRead
  13. xpkmaster.library/XpkUnpack
  14. xpkmaster.library/XpkUnpackTags
  15. xpkmaster.library/XpkWrite
  16. xpkmaster.library/--tags--
  17. xpkmaster.library/--progress--
  18.  
  19. xpkmaster.library/XpkClose                         xpkmaster.library/XpkClose
  20.  
  21.     NAME
  22.     XpkClose - Close an XPK-File
  23.  
  24.     SYNOPSIS
  25.     err = XpkClose( xfh )
  26.     D0        A0
  27.  
  28.     LONG  XpkClose(struct XpkFH *)
  29.  
  30.     FUNCTION
  31.     Frees all resources associated with packing or unpacking an
  32.     XPK-File. Note that this may well fail, especially on packing,
  33.     since additional writes have to be made here.
  34.  
  35.     INPUT
  36.     xfh    - The XpkFH obtained from XpkOpen()
  37.  
  38.     RESULT
  39.     err     - Global Xpk error code
  40.  
  41.     SEE ALSO
  42.     XpkOpen(), XpkRead(), XpkWrite()
  43. xpkmaster.library/XpkExamine                     xpkmaster.library/XpkExamine
  44.  
  45.     NAME
  46.     XpkExamine - Get information about a compressed file
  47.  
  48.     SYNOPSIS
  49.     err = XpkExamine(fib, tags)
  50.     D0          A0   A1
  51.  
  52.     LONG  XpkExamine(struct XpkFib *, struct TagItem *)
  53.  
  54.     FUNCTION
  55.     Returns information about compressed data. The output is written
  56.     to the XpkFib structure whose address is passed with the mandatory
  57.     XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note
  58.     that the file position of the in hook will not be altered.
  59.  
  60.     INPUT
  61.     tags    - Pointer to an array of struct TagItem. You may use 
  62.           either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook
  63.           tag.
  64.  
  65.     RESULT
  66.     err    - Global Xpk error code
  67.  
  68.     SEE ALSO
  69.     libraries/xpk.h, xDir.c
  70.  
  71. xpkmaster.library/XpkExamineTags             xpkmaster.library/XpkExamineTags
  72.  
  73.     NAME
  74.     XpkExamineTags - Get information about a compressed file
  75.  
  76.     SYNOPSIS
  77.     err = XpkExamineTags(fib, tag1, val1, tag2, val2, .... , TAG_DONE )
  78.     D0
  79.  
  80.     LONG  XpkExamineTags(ULONG, ... );
  81.  
  82.     FUNCTION
  83.     Same as XpkExamine(), but tags passed on stack. This is a link-
  84.     library function, you'll need to link with xpk<compiler>.lib .
  85.  
  86.     SEE ALSO
  87.     XpkExamine()
  88. xpkmaster.library/XpkOpen                           xpkmaster.library/XpkOpen
  89.  
  90.     NAME
  91.     XpkOpen - Open a compressed file for partial reading
  92.  
  93.     SYNOPSIS
  94.     err = XpkOpen(xfh,tags)
  95.     D0          A0   A1
  96.  
  97.     LONG  XpkOpen( struct XpkFH **xfh,struct TagItem *)
  98.  
  99.     FUNCTION
  100.     Using XpkOpen you can read or write an XPK-File without ever having
  101.     all of the file present in RAM. On reading, you cannot pick the 
  102.     size of the chunks; they're given by the file to be decompressed
  103.     and may be up to the whole size of the file.
  104.  
  105.     INPUT
  106.     xfh    - Address of a pointer to struct XpkFH
  107.     tags    - Specifying XPK_PackMethod will chose packing mode for
  108.           this filehandle. Only In-tags are permitted in case
  109.           of unpacking, and only Out-tags are in case of packing.
  110.           Anything else will yield undefined results. Progress
  111.           reports not supported. When packing, you must supply
  112.           XPK_InLen as well.
  113.  
  114.     RESULT
  115.     xfh    - The filehandle. Consists of an xfib and some private
  116.           information. The NLen field in the xfh indicates the
  117.           length of the next chunk.
  118.     err    - Global Xpk error code. If nonzero, no xfh was allocated.
  119.           Check the XPK_GetError to see how to get a full err msg.
  120.  
  121.     SEE ALSO
  122.     XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/tags, examples/
  123.  
  124. xpkmaster.library/XpkPack                           xpkmaster.library/XpkPack
  125.  
  126.     NAME
  127.     XpkPack - Compress a data stream
  128.  
  129.     SYNOPSIS
  130.     err = XpkPack(tags)
  131.     D0           A0
  132.  
  133.     LONG  XpkPack(struct TagItem *);
  134.  
  135.     FUNCTION
  136.     Compresses a file or a memory area to a different file or memory
  137.     area. You need to specify at least one XPK_In... tag, at least
  138.     one XPK_Out... tag, plus XPK_PackMethod.
  139.  
  140.     INPUT
  141.     tags    - Pointer to an array of struct TagItem. See xpkmaster/tags
  142.  
  143.     RESULT
  144.     err    - Global Xpk error code, see xpk.h. Check the XPK_GetError 
  145.           to see how to get a full err msg.
  146.  
  147.     SEE ALSO
  148.     xpkmaster.library/tags, xpk.c
  149.  
  150. xpkmaster.library/XpkPackTags                   xpkmaster.library/XpkPackTags
  151.  
  152.     NAME
  153.     XpkPackTags - Compress a data stream
  154.  
  155.     SYNOPSIS
  156.     err = XpkPackTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  157.     D0
  158.  
  159.     LONG  XpkPackTags(ULONG, ... );
  160.  
  161.     FUNCTION
  162.     Same as XpkPack(), but tags passed on stack. This is a link-
  163.     library function, you'll need to link with xpk<compiler>.lib .
  164.  
  165.     SEE ALSO
  166.     XpkPack()
  167. xpkmaster.library/XpkQuery                         xpkmaster.library/XpkQuery
  168.  
  169.     NAME
  170.     XpkQuery - Gain information about packers
  171.  
  172.     SYNOPSIS
  173.     err = XpkQuery( tags )
  174.     D0         A0
  175.  
  176.     LONG  XpkQuery( tags );
  177.  
  178.     FUNCTION
  179.     Finds out a list of available packers or various parameters of a
  180.     packer.  When using the tag XPK_PackersQuery, you must supply a
  181.     XpkPackerList structure and will receive a list of available
  182.     packers.  The second possibility, XPK_PackerQuery, expects a
  183.     pointer to a XpkPackerInfo structure which will be filled in with
  184.     information about a packer, and XPK_ModeQuery fills in a XpkMode
  185.     structure with information about some mode (or the default mode)
  186.     of a packer.  XPK_PackMethod must be present among the tags for
  187.     the latter two, and XPK_PackMode can be for ModeQuery.
  188.  
  189.     RESULT
  190.     err     - Global Xpk error code. XPK_GetError also supported
  191.  
  192.     SEE ALSO
  193.     libraries/xpk.h
  194. xpkmaster.library/XpkQueryTags                 xpkmaster.library/XpkQueryTags
  195.  
  196.     NAME
  197.     XpkQueryTags - Gain information about packers
  198.  
  199.     SYNOPSIS
  200.     err = XpkQueryTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  201.     D0
  202.  
  203.     LONG  XpkQueryTags(ULONG, ... );
  204.  
  205.     FUNCTION
  206.     Same as XpkQuery(), but tags passed on stack. This is a link-
  207.     library function, you'll need to link with xpk<compiler>.lib .
  208.  
  209.     SEE ALSO
  210.     XpkQuery()
  211. xpkmaster.library/XpkRead                           xpkmaster.library/XpkRead
  212.  
  213.     NAME
  214.     XpkRead - Unpack one part of an XPK-File
  215.  
  216.     SYNOPSIS
  217.     read = XpkRead( xfh, buf, len )
  218.     D0        A0   A1   D0
  219.  
  220.     LONG  XpkRead(struct XpkFH *, UBYTE *, LONG)
  221.  
  222.     FUNCTION
  223.     Reads one chunk from an XPK-file and decompresses it to the
  224.     memory area indicated.
  225.  
  226.     INPUT
  227.     xfh    - The XpkFH obtained from XpkOpen(). It must be a read-
  228.           handle, ie. there was no XPK_PackMethod tag among the
  229.           tags passed to XpkOpen().
  230.     buf    - The memory area to write the destination to
  231.     len    - The number uncompressed bytes to output. Note that you
  232.           can't choose these freely but must take them from 
  233.           the NLen field in the xfh.
  234.  
  235.     RESULT
  236.     read    - The number of bytes read. 0 indicates EOF, negative
  237.           numbers are global error codes. Long error messages 
  238.           written to buffer passed through XPK_GetError in 
  239.           XpkOpen(). This number of bytes read will usually be
  240.           smaller than the number requested!
  241.  
  242.     SEE ALSO
  243.     XpkOpen(), XpkWrite(), XpkClose(), examples/
  244. xpkmaster.library/XpkUnpack                       xpkmaster.library/XpkUnpack
  245.  
  246.     NAME
  247.     XpkUnpack - Decompress a data stream
  248.  
  249.     SYNOPSIS
  250.     err = XpkUnpack(tags)
  251.     D0           A0
  252.  
  253.     LONG  XpkUnpack(struct TagItem *);
  254.  
  255.     FUNCTION
  256.     Decompresses a file or a memory area to a different file or memory
  257.     area. You need to specify at least one XPK_In... tag, at least
  258.     one XPK_Out... tag.
  259.  
  260.     INPUT
  261.     tags   - Pointer to an array of struct TagItem. See xpkmaster/tags
  262.  
  263.     RESULT
  264.     err    - Global Xpk error code.
  265.  
  266.     SEE ALSO
  267.     xpkmaster.library/tags
  268.  
  269. xpkmaster.library/XpkUnpackTags               xpkmaster.library/XpkUnpackTags
  270.  
  271.     NAME
  272.     XpkUnpackTags - Decompress a data stream
  273.  
  274.     SYNOPSIS
  275.     err = XpkUnpackTags(tag1, val1, tag2, val2, .... , TAG_DONE )
  276.     D0
  277.  
  278.     LONG  XpkUnpackTags(ULONG, ... );
  279.  
  280.     FUNCTION
  281.     Same as XpkUnpack(), but tags passed on stack. This is a link-
  282.     library function, you'll need to link with xpk<compiler>.lib.
  283.  
  284.     SEE ALSO
  285.     XpkUnpack()
  286. xpkmaster.library/XpkWrite                         xpkmaster.library/XpkWrite
  287.  
  288.     NAME
  289.     XpkWrite - Pack one part of an XPK-File
  290.  
  291.     SYNOPSIS
  292.     read = XpkWrite( xfh, buf, len )
  293.     D0         A0   A1   D0
  294.  
  295.     LONG  XpkWrite(struct XpkFH *, UBYTE *, LONG)
  296.  
  297.     FUNCTION
  298.     Compresses the memory area indicated and writes it to an
  299.     XPK-File.
  300.  
  301.     INPUT
  302.     xfh    - The XpkFH obtained from XpkOpen(). Must be a write-
  303.           handle, ie. XPK_PackMethod must have been among the
  304.           tags passed to XpkOpen().
  305.     buf    - The memory area to compress
  306.     len    - The number bytes to compress. Note you may not choose
  307.           them freely, you must always deliver as many bytes
  308.           as the NLen field of the XFH indicates. You may try
  309.           to influence it by passing XPK_ChunkLen to XpkOpen().
  310.           Important: The first chunk written *must* be the
  311.           biggest!
  312.  
  313.     RESULT
  314.     written    - The number of bytes written. 0 indicates EOF, negative
  315.           numbers are global error codes. Error messages are 
  316.           written to buffer passed through XPK_GetError in 
  317.           XpkOpen().
  318.  
  319.     SEE ALSO
  320.     XpkOpen(), XpkRead(), XpkClose(), examples/
  321. xpkmaster.library/--tags--                         xpkmaster.library/--tags--
  322.  
  323.     THE TAGS FOR XpkPack() AND XpkUnpack()
  324.  
  325.     THE INPUT TAGS. One of the four must be present.
  326.  
  327.     XPK_InName  (char *)
  328.         Name of file to (de)compress. On packing, XPK_InLen can be 
  329.         specified in order to pack only the first N bytes. On de-
  330.         compression, only one file will be decompressed, even if 
  331.         there are additional data at the end.
  332.  
  333.     XPK_InFH    (BPTR)
  334.         File handle to (de)compress from. It is not necessary that
  335.         the handle is at the beginning of the file. Otherwise same
  336.         rules as in XPK_InName apply.
  337.  
  338.     XPK_InBuf   (UBYTE *)
  339.         Memory block to (de)compress. If you use this one, you 
  340.         have to specify InLen as well.
  341.  
  342.     XPK_InHook  (struct Hook *)
  343.         Hookfunc to deliver data for (de)compression. See special
  344.         chapter on I/O hook functions. Must also supply XPK_InLen.
  345.  
  346.     IN ADDITION
  347.  
  348.     XPK_InLen   (LONG)
  349.         Specifies the number of bytes to read when compressing.
  350.         gnored on decompression.
  351.  
  352.  
  353.     THE OUTPUT TAGS. One of the five must be present.
  354.  
  355.     XPK_OutName      (char *)
  356.         Name of file write (de)compressed data to.
  357.  
  358.     XPK_OutFH        (BPTR)
  359.         File handle to append (de)compressed data to.
  360.  
  361.     XPK_OutBuf       (APTR)
  362.         The memory block to write (de)compressed data to. Must also
  363.         supply XPK_OutBufLen. On packing, its size must be at least
  364.         inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be
  365.         outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note
  366.         that this buffer must be word aligned.
  367.  
  368.     XPK_GetOutBuf    (APTR *)
  369.         Allocates a block of appropriate size and stores a pointer to
  370.         it in the variable pointed to by ti_Data. Must also supply 
  371.         XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType.
  372.  
  373.     XPK_OutHook      (struct Hook *)
  374.         Hookfunc to accept (de)compressed data. See special chapter
  375.         on I/O hook functions.
  376.  
  377.     IN ADDITION
  378.  
  379.     XPK_OutBufLen    (LONG)
  380.         The length of the output buffer you supply using XPK_OutBuf.
  381.         For decompression, must be decompressed size (see XpkExamine())
  382.         plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN.
  383.  
  384.     XPK_GetOutLen    (LONG *)
  385.         Stores the total length of the (de)compressed data in the variable
  386.         pointed to by ti_Data. Note: V2 of xpkmaster required for correct
  387.         operation on compression.
  388.  
  389.     XPK_GetOutBufLen (LONG *)
  390.         Stores the length of the buffer allocated for the data in the
  391.         variable pointed to by ti_Data. FreeMem() the buffer you  get
  392.         from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen.
  393.         Note: For the number of bytes written, refer to XPK_GetOutLen!
  394.  
  395.     XPK_OutMemType   (LONG)
  396.         The type of memory to use for the output buffer.
  397.  
  398.  
  399.     PACKING TAGS
  400.  
  401.     XPK_PackMethod   (char *)
  402.         Use indicated method for packing. This would be a four
  403.         letter string in most cases, plus an optional dot and 
  404.         a packing mode. See XPK_PackMode
  405.  
  406.     XPK_PackMode     (LONG)
  407.         Packing mode for sublib to use. Range is 0...100, where 100 is
  408.         most efficient.
  409.  
  410.     XPK_StepDown     (BOOL)
  411.         Reduce packing efficiency to save mem if necessary.
  412.  
  413.     XPK_ChunkSize    (LONG)
  414.         Chunk size to try to pack with. May be altered by the
  415.         master library.
  416.  
  417.  
  418.     QUERY TAGS
  419.  
  420.     XPK_PackersQuery (struct XpkPackerList *)
  421.         Returns an array of available packers names in the XPLIST
  422.         structure whose address is stored in the ti_Data field
  423.         of this tag.
  424.  
  425.     XPK_PackerQuery  (struct XpkPackerInfo *)
  426.         Returns information about one single packer in the XPINFO
  427.         structure whose address is stored in the ti_Data field
  428.         of this tag. See libraries/xpk.h for the meaning of the
  429.         fields therein. You must also supply XPK_PackMode.
  430.  
  431.     XPK_ModeQuery    (struct XpkMode *)
  432.         Returns information about one single packer mode in the 
  433.         XPINFO structure whose address is stored in the ti_Data 
  434.         field of this tag. See libraries/xpk.h for the meaning of 
  435.         the fields therein. You must also supply XPK_PackMethod
  436.         and optionally XPK_PackMode (or a mode in the PackMethod
  437.         string), otherwise the default mode will be used.
  438.  
  439.  
  440.     OTHER TAGS
  441.  
  442.     XPK_GetError     (char *)
  443.         Write error msg to the buffer passed. The buffer must be of 
  444.         size XPKERRMSGSIZE.
  445.  
  446.     XPK_ShortError    (BOOL)
  447.         Don't include activity and file name in error messages.
  448.  
  449.     XPK_Password     (char *)
  450.         Use password for en- or decoding. Passing a NULL pointer or
  451.         zero length string is equivalent to omitting this tag.
  452.  
  453.     XPK_ChunkHook    (struct Hook *)
  454.         Hook function to call between chunks. Can print a progress
  455.         report, and if it returns a nonzero value, the (de)compression
  456.         will be aborted. See special chapter on chunk functions.
  457.  
  458.     XPK_PassThru     (BOOL)
  459.         If true, data will just be handed trough on decompression if they
  460.         were not packed. Otherwise you get XPKERR_NOTPACKED.
  461.  
  462.     XPK_TaskPri      (UBYTE)
  463.         The task priority to use during the (de)crunching. Use -1 for
  464.         background decompression.
  465.  
  466.     XPK_FileName     (STRPTR)
  467.         The name to print in the progress report. If none is given, the
  468.         InName will be used when packing and the OutName when unpacking.
  469. xpkmaster.library/--progress--                 xpkmaster.library/--progress--
  470.  
  471.     THE PROGRESS REPORT HOOK
  472.  
  473.     The progress report function is a standard hook function that will
  474.     be called after every chunk (de)compressed. This will be about 
  475.     every 30K, or just twice if the file format is not split in chunks.
  476.     If the field h_Entry in the hook is set, it will be called with 
  477.     the hook itself in a0 and the progress report structure in a1.
  478.     If your compiler does not support direct calling in registers,
  479.     it must have a library function that puts the arguments that
  480.     puts the arguments wherever the functions needs them and call it.
  481.     A4 is guaranteed to be saved so it is not necessary to provide
  482.     geta4() or __saveds in C programs. If the progress report function
  483.     returns a nonzero value, (de)compression aborts.  Note: it is YOUR
  484.     responsibility to turn off your compiler's CTRL-C-handling e.g. if 
  485.     you do printf()s in the chunk function!
  486.  
  487.     THE PROGRESS REPORT STRUCTURE
  488.  
  489.     LONG    Type        : XPKPROG_START, XPKPROG_MID or XPKPROG_END
  490.     STRPTR    PackerName    : Brief name of packer being used
  491.     STRPTR    PackerLongName    : Descriptive name of packer being used
  492.     STRPTR    Activity    : Packing/unpacking message
  493.     STRPTR    FileName    : Name of file being processed, if available
  494.     LONG    CCur        : Amount of packed data already processed
  495.     LONG    UCur        : Amount of unpacked data already processed
  496.     LONG    ULen        : Amount of unpacked data in file
  497.     LONG    CF        : Compression factor so far
  498.     LONG    Done        : Percentage done already
  499.     LONG    Speed        : Bytes per second, from beginning of stream
  500.